home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 21 / AACD 21.iso / AACD / Utilities / Ghostscript / src / imain.h < prev    next >
Encoding:
C/C++ Source or Header  |  2001-01-01  |  9.7 KB  |  262 lines
  1. /* Copyright (C) 1995, 1996, 1999 Aladdin Enterprises.  All rights reserved.
  2.   
  3.   This file is part of AFPL Ghostscript.
  4.   
  5.   AFPL Ghostscript is distributed with NO WARRANTY OF ANY KIND.  No author or
  6.   distributor accepts any responsibility for the consequences of using it, or
  7.   for whether it serves any particular purpose or works at all, unless he or
  8.   she says so in writing.  Refer to the Aladdin Free Public License (the
  9.   "License") for full details.
  10.   
  11.   Every copy of AFPL Ghostscript must include a copy of the License, normally
  12.   in a plain ASCII text file named PUBLIC.  The License grants you the right
  13.   to copy, modify and redistribute AFPL Ghostscript, but only under certain
  14.   conditions described in the License.  Among other things, the License
  15.   requires that the copyright notice and this notice be preserved on all
  16.   copies.
  17. */
  18.  
  19. /*$Id: imain.h,v 1.2 2000/09/19 19:00:44 lpd Exp $ */
  20. /* Interface to imain.c */
  21. /* Requires <stdio.h>, stdpre.h, gsmemory.h, gstypes.h, iref.h */
  22.  
  23. #ifndef imain_INCLUDED
  24. #  define imain_INCLUDED
  25.  
  26. #include "gsexit.h"        /* exported by imain.c */
  27.  
  28. /*
  29.  * This file defines the intended API between client front ends
  30.  * (such as imainarg.c, the command-line-driven front end)
  31.  * and imain.c, which provides top-level control of the interpreter.
  32.  */
  33.  
  34. /* ================ Types ================ */
  35.  
  36. /*
  37.  * Currently, the interpreter has a lot of static variables, but
  38.  * eventually it will have none, so that clients will be able to make
  39.  * multiple instances of it.  In anticipation of this, many of the
  40.  * top-level API calls take an interpreter instance (gs_main_instance *)
  41.  * as their first argument.
  42.  */
  43. #ifndef gs_main_instance_DEFINED
  44. #  define gs_main_instance_DEFINED
  45. typedef struct gs_main_instance_s gs_main_instance;
  46. #endif
  47.  
  48. /* ================ Exported procedures from imain.c ================ */
  49.  
  50. /* ---------------- Instance creation ---------------- */
  51.  
  52. /*
  53.  * As noted above, multiple instances are not supported yet:
  54.  */
  55. /*gs_main_instance *gs_main_alloc_instance(P1(gs_memory_t *)); */
  56. /*
  57.  * Instead, we provide only a default instance:
  58.  */
  59. gs_main_instance *gs_main_instance_default(P0());
  60.  
  61. /* ---------------- Initialization ---------------- */
  62.  
  63. /*
  64.  * The interpreter requires three initialization steps, called init0,
  65.  * init1, and init2.  These steps must be done in that order, but
  66.  * init1 may be omitted.
  67.  */
  68.  
  69. /*
  70.  * Since gsio.h (which is included in many other header files)
  71.  * redefines stdin/out/err, callers need a way to get the "real"
  72.  * stdio files to pass to init0 if they wish to do so.
  73.  */
  74. void gs_get_real_stdio(P1(FILE * stdfiles[3]));
  75.  
  76. /*
  77.  * init0 records the files to be used for stdio, and initializes the
  78.  * graphics library, the file search paths, and other instance data.
  79.  */
  80. int gs_main_init0(P5(gs_main_instance *minst, FILE *in, FILE *out, FILE *err,
  81.              int max_lib_paths));
  82.  
  83. /*
  84.  * init1 initializes the memory manager and other internal data
  85.  * structures such as the name table, the token scanner tables,
  86.  * dictionaries such as systemdict, and the interpreter stacks.
  87.  */
  88. int gs_main_init1(P1(gs_main_instance * minst));
  89.  
  90. /*
  91.  * init2 finishes preparing the interpreter for use by running
  92.  * initialization files with PostScript procedure definitions.
  93.  */
  94. int gs_main_init2(P1(gs_main_instance * minst));
  95.  
  96. /*
  97.  * The runlibfile operator uses a search path, as described in
  98.  * Use.htm, for looking up file names.  Each interpreter instance has
  99.  * its own search path.  The following call adds a directory or set of
  100.  * directories to the search path; it is equivalent to the -I command
  101.  * line switch.  It may be called any time after init0.
  102.  */
  103. int gs_main_add_lib_path(P2(gs_main_instance * minst, const char *path));
  104.  
  105. /*
  106.  * Under certain internal conditions, the search path may temporarily
  107.  * be in an inconsistent state; gs_main_set_lib_paths takes care of
  108.  * this.  Clients should never need to call this procedure, and
  109.  * eventually it may be removed.
  110.  */
  111. int gs_main_set_lib_paths(P1(gs_main_instance * minst));
  112.  
  113. /*
  114.  * Open a PostScript file using the search path.  Clients should
  115.  * never need to call this procedure, since gs_main_run_file opens the
  116.  * file itself, and eventually the procedure may be removed.
  117.  */
  118. int gs_main_lib_open(P3(gs_main_instance * minst, const char *fname,
  119.             ref * pfile));
  120.  
  121. /*
  122.  * Here we summarize the C API calls that correspond to some of the
  123.  * most common command line switches documented in Use.htm, to help
  124.  * clients who are familiar with the command line and are starting to
  125.  * use the API.
  126.  *
  127.  *      -d/D, -s/S (for setting device parameters like OutputFile)
  128.  *              Use the C API for device parameters documented near the
  129.  *              end of gsparam.h.
  130.  *
  131.  *      -d/D (for setting Boolean parameters like NOPAUSE)
  132.  *              { ref vtrue;
  133.  *                make_true(&vtrue);
  134.  *                dict_put_string(systemdict, "NOPAUSE", &vtrue);
  135.  *              }
  136.  *      -I
  137.  *              Use gs_main_add_lib_path, documented above.
  138.  *
  139.  *      -A, -A-
  140.  *              Set gs_debug['@'] = 1 or 0 respectively.
  141.  *      -E, -E-
  142.  *              Set gs_debug['#'] = 1 or 0 respectively.
  143.  *      -Z..., -Z-...
  144.  *              Set gs_debug[c] = 1 or 0 respectively for each character
  145.  *              c in the string.
  146.  */
  147.  
  148. /* ---------------- Execution ---------------- */
  149.  
  150. /*
  151.  * After initializing the interpreter, clients may pass it files or
  152.  * strings to be interpreted.  There are four ways to do this:
  153.  *      - Pass a file name (gs_main_run_file);
  154.  *      - Pass a C string (gs_main_run_string);
  155.  *      - Pass a string defined by pointer and length
  156.  *              (gs_main_run_string_with_length);
  157.  *      - Pass strings piece-by-piece
  158.  *              (gs_main_run_string_begin/continue/end).
  159.  *
  160.  * The value returned by the first three of these calls is
  161.  * 0 if the interpreter ran to completion, e_Quit for a normal quit,
  162.  * or e_Fatal for a non-zero quit or a fatal error.
  163.  * e_Fatal stores the exit code in the third argument.
  164.  * The str argument of gs_main_run_string[_with_length] must be allocated
  165.  * in non-garbage-collectable space (e.g., by malloc or gs_malloc,
  166.  * or statically).
  167.  */
  168. int gs_main_run_file(P5(gs_main_instance * minst,
  169.             const char *fname,
  170.             int user_errors, int *pexit_code,
  171.             ref * perror_object));
  172. int gs_main_run_string(P5(gs_main_instance * minst,
  173.               const char *str,
  174.               int user_errors, int *pexit_code,
  175.               ref * perror_object));
  176. int gs_main_run_string_with_length(P6(gs_main_instance * minst,
  177.                       const char *str, uint length,
  178.                       int user_errors, int *pexit_code,
  179.                       ref * perror_object));
  180.  
  181. /*
  182.  * Open the file for gs_main_run_file.  This is an internal routine
  183.  * that is only exported for some special clients.
  184.  */
  185. int gs_main_run_file_open(P3(gs_main_instance * minst,
  186.                  const char *file_name, ref * pfref));
  187.  
  188. /*
  189.  * The next 3 procedures provide for feeding input to the interpreter
  190.  * in arbitrary chunks, unlike run_string, which requires that each string
  191.  * be a properly formed PostScript program fragment.  To use them:
  192.  *      Call run_string_begin.
  193.  *      Call run_string_continue as many times as desired,
  194.  *        stopping if it returns anything other than e_NeedInput.
  195.  *      If run_string_continue didn't indicate an error or a quit
  196.  *        (i.e., a return value other than e_NeedInput), call run_string_end
  197.  *        to provide an EOF indication.
  198.  * Note that run_string_continue takes a pointer and a length, like
  199.  * run_string_with_length.
  200.  */
  201. int gs_main_run_string_begin(P4(gs_main_instance * minst, int user_errors,
  202.                 int *pexit_code, ref * perror_object));
  203. int gs_main_run_string_continue(P6(gs_main_instance * minst,
  204.                    const char *str, uint length,
  205.                    int user_errors, int *pexit_code,
  206.                    ref * perror_object));
  207. int gs_main_run_string_end(P4(gs_main_instance * minst, int user_errors,
  208.                   int *pexit_code, ref * perror_object));
  209.  
  210. /* ---------------- Operand stack access ---------------- */
  211.  
  212. /*
  213.  * The following procedures are not used in normal operation;
  214.  * they exist only to allow clients driving the interpreter through the
  215.  * gs_main_run_xxx procedures to push parameters quickly and to get results
  216.  * back.  The push procedures return 0, e_stackoverflow, or e_VMerror;
  217.  * the pop procedures return 0, e_stackunderflow, or e_typecheck.
  218.  *
  219.  * Procedures to push values on the operand stack:
  220.  */
  221. int gs_push_boolean(P2(gs_main_instance * minst, bool value));
  222. int gs_push_integer(P2(gs_main_instance * minst, long value));
  223. int gs_push_real(P2(gs_main_instance * minst, floatp value));
  224. int gs_push_string(P4(gs_main_instance * minst, byte * chars, uint length,
  225.               bool read_only));
  226.  
  227. /*
  228.  * Procedures to pop values from the operand stack:
  229.  */
  230. int gs_pop_boolean(P2(gs_main_instance * minst, bool * result));
  231. int gs_pop_integer(P2(gs_main_instance * minst, long *result));
  232. int gs_pop_real(P2(gs_main_instance * minst, float *result));
  233.  
  234. /* gs_pop_string returns 1 if the string is read-only. */
  235. int gs_pop_string(P2(gs_main_instance * minst, gs_string * result));
  236.  
  237. /* ---------------- Debugging ---------------- */
  238.  
  239. /*
  240.  * Print an error mesage including the error code, error object (if any),
  241.  * and operand and execution stacks in hex.  Clients will probably
  242.  * never call this.
  243.  */
  244. void gs_main_dump_stack(P3(gs_main_instance *minst, int code,
  245.                ref * perror_object));
  246.  
  247. /* ---------------- Termination ---------------- */
  248.  
  249. /*
  250.  * Terminate the interpreter by closing all devices and releasing all
  251.  * allocated memory.  Currently, because of some technical problems
  252.  * with statically initialized data, it is not possible to reinitialize
  253.  * the interpreter after terminating it; we plan to fix this as soon as
  254.  * possible.
  255.  *
  256.  * Note that calling gs_exit (defined in gsexit.h) automatically calls
  257.  * gs_main_finit for the default instance.
  258.  */
  259. void gs_main_finit(P3(gs_main_instance * minst, int exit_status, int code));
  260.  
  261. #endif /* imain_INCLUDED */
  262.